Agently is an agentic application framework with a ready-to-run server, CLI, web application, and native iOS and Android shells. It brings together configurable agents, models, tools, knowledge, durable conversations, and interactive workspaces.
Build assistants that work with your APIs and data, ask for missing information or approvals, delegate tasks, produce reports, and continue scheduled work. Application behavior and appearance are defined by the workspace; the framework is not tied to one business domain.
Agently provides the execution engine and the application around it. A workspace connects agent instructions, model choices, knowledge, tools and UI metadata, so the same assistant can reason over data, ask for approval and present an interactive result within one conversation.
- Declarative applications. Define agents, intent profiles, tool bundles, skills, templates, data sources and application windows as workspace resources. Reuse configuration across assistants and customize navigation, layout and appearance for your application.
- Work that survives the session. Persist conversations, tool calls and run state; coordinate queued turns, asynchronous operations, linked agents, goals and schedules. Reopen work and recover from interruption using saved state.
- Governed access to tools and data. Combine internal services and MCP tools under common dispatch, authorization and approval policies. Use forms and lookups to collect precise inputs before execution.
- Results people can use. Go beyond text with live tool feeds, tables, charts, reports and hosted workspaces. Keep these results associated with their conversation and expose them through web, native mobile or custom clients.
- An extensible runtime. Embed Core in your Go service or use the assembled server. Choose providers and integrations, add tools and metadata, and build clients against the AG-UI protocol and application APIs.
Agently assembles Agently Core, which owns execution and persistence, with Forge, which renders metadata-driven interfaces.
A prompt enters an authenticated conversation. The runtime resolves the agent, model, instructions and available tools, assembles knowledge and history, then runs the model/tool loop. Tool policy can block execution or request approval; elicitation can collect missing inputs. Messages, calls and execution state are persisted as work progresses. Clients render the canonical results and can reattach after a disconnect without submitting the prompt again.
AG-UI connects clients to the conversation runtime: runs, streamed messages, tool activity, state and interactive continuation. Agently extensions carry workspace presentation, tool feeds, goals, approvals and queue controls. The BFF applies authentication across this interaction and the application APIs for history, metadata, uploads, reporting and management. All clients share the same execution and persistence services; Forge renders the workspace's authored UI.
| Area | What you can build or configure |
|---|---|
| Agents and orchestration | Agent/model selection, intake profiles, prompt binding, iterative model/tool execution, parallel tools, linked agents and follow-up chains |
| Models and knowledge | Multiple model providers, embedding-based knowledge retrieval, budgeted prompt augmentation, instructions, skills and reusable templates |
| Tools and integration | Internal tools and MCP servers, bundles and policies, resources, optional MCP exposure and A2A endpoints |
| Conversations | Durable history, streaming, attachments, queued turns, cancellation, recovery and continuation |
| Human interaction | Server-driven forms, lookups, input refinement, immediate or queued tool approval and editable approval inputs |
| Autonomous work | Conversation goals, usage budgets, controller-owned continuation, schedules and long-running asynchronous operations |
| Application UI | Workspace-defined navigation, windows, layouts, actions, themes, CSS, fonts, inline or detached tool feeds and MCP Apps |
| Reporting | Authored report definitions, scoped datasets, charts and tables, durable report lifecycle, saved results and explicit export/publication |
| Security and operations | Local/JWT/OAuth authentication, BFF sessions, scoped MCP credentials, SQLite/MySQL persistence, cleanup and separate scheduler runners |
| Clients and extension | Go, TypeScript, Swift and Kotlin SDKs; web/mobile shells; custom tools, providers, runtime integrations and presentation |
Provider capabilities vary. The configured core adapters include OpenAI, Vertex AI Gemini/Claude, Bedrock Converse/Claude, Grok, InceptionLabs and Ollama. Uploads and resource tools support file inspection and extraction; multimodal model input and optional speech transcription depend on the chosen adapter.
Context management derives the model-visible history from durable conversation state. Limits, pruning and overflow recovery are configurable; proactive percentage-based compaction is an optional agent setting. See the context guide and compaction settings.
Requires Go 1.25.8 or newer. Configure a workspace model and its provider credentials before making a model request. The Go module selects the server's runtime dependencies.
go build -o ./bin/agently ./agently
./bin/agently serve -a :8080 -w /path/to/workspace
./bin/agently query --api http://localhost:8080 -q "Summarize the project documentation"
./bin/agently list-tools --api http://localhost:8080The query CLI prints the conversation and AG-UI run IDs before observing the answer. If an event stream disconnects, it reattaches to that same run using the last event cursor; it does not submit the prompt again. To observe a known run later, use the same authentication options with:
./bin/agently query --api http://localhost:8080 --conv <conversation-id> --attach-run <run-id>Add --after-event-id <cursor> when continuing an already consumed stream.
Attach mode cannot include a new query, attachment, context, or model override.
The application workspace defaults to .agently in the working directory; AGENTLY_WORKSPACE or
serve --workspace selects another root. It is the authored configuration of
an application, separate from the conversation-owned UI workspace that holds
open reports and windows.
workspace/
config.yaml # Application defaults and service configuration
agents/ # Prompts, model selection, knowledge and tools
models/ # Model/provider definitions
embedders/ # Embedding providers
mcp/ # MCP client connections
tools/bundles/ # Tool groups and approval policy
tools/instructions/ # Tool-specific instructions
intents/ # Scenario profiles and routing context
skills/ # Reusable skill resources
templates/ # Output templates and template bundles
workflows/ # Workflow resources
feeds/ # Tool-output feed definitions
oauth/ # Identity-provider resources
a2a/ # Agent-to-agent definitions
callbacks/ # Interaction callbacks
extension/forge/
datasources/ # Data bindings for forms and views
dialogs/ # Dialog definitions
lookups/ # Lookup/picker configuration
models/ # UI model metadata
windows/ # Hosted window definitions
Select resource IDs in config.yaml, for example:
default:
agent: assistant
model: configured-model
appName: Project Assistant
ui:
composer:
allowAgentSelection: true
allowModelSelection: trueDefine agents/assistant.yaml and the matching model resource. An agent's
instructions can use prompt bindings; its configuration can select knowledge,
tool bundles, skills, templates and execution limits. Provider credentials and
model options belong to the model/provider configuration, not the prompt.
For example, the agent can start with an explicitly bound task prompt:
id: assistant
name: Project Assistant
temperature: 0
parallelToolCalls: true
prompt:
engine: go
text: "{{.Task.Prompt}}"Tool bundles determine which operations the agent can use and their approval rules. A bundle can require queued approval for a tool group:
match:
- name: "project:*"
approval:
mode: queueThese are configuration fragments, not a complete provider setup. The workspace and agent authoring guides describe these contracts.
Workspace YAML can import reusable fragments and parameterize them in a scoped context. Exact parameter substitutions preserve YAML types. Resources can be managed as versioned files or through workspace resource APIs. Loading and reload behavior are handled by the resource repositories and their consumers.
UI customization is also declarative: navigation, starter prompts, windows, controls, data sources and actions are driven by metadata. Web, iOS and Android can resolve platform/form-factor-specific definitions. Named themes, fonts and scoped workspace CSS control appearance; web CSS remains web styling, while native renderers consume their supported theme and metadata contracts. Inline tool feeds and conversation-owned windows have distinct ownership and placement. See workspace UI and UI ownership.
For integration beyond configuration, register internal tool services or connect MCP servers, add resource finders and application handlers through Core, and compose Forge with application-owned data/action connectors. Forge is a separate data-driven UI framework; Agently owns the agent runtime, authentication and conversation coordination around it.
Use serve --help and query --help for deployment and authentication options.
The server supports local sessions, JWT and OAuth modes. Configure the identity
provider and tool policy for your deployment. The coarse --policy setting
supports auto, ask and deny; tool-bundle rules refine approval behavior.
SQLite is the workspace default; MySQL uses a configured connection and
versioned schema. Scheduler API and runner roles can be deployed separately.
Key settings include AGENTLY_DB_DRIVER, AGENTLY_DB_DSN,
AGENTLY_SCHEDULER_API, AGENTLY_SCHEDULER_RUNNER and the cleanup policies.
Conversation, execution and report state share the application's persistence
lifecycle, including authorization, retention and cleanup.
The guides below are tracked in Git. Framework guides live in Agently Core; application and platform guides live here. Start with architecture, workspace configuration and the tool system, then follow the guide for your use case.
| Topic | Guides |
|---|---|
| Architecture and execution | Core architecture, agent orchestration, planning/intake |
| Agent authoring | Workspace configuration, intent profiles, prompt binding, skills, templates |
| Models, knowledge and files | Providers, knowledge augmentation, embeddings, resources, speech |
| Tools and interoperability | Tool system, internal tools, MCP integration, A2A |
| Human input and approvals | Elicitation, lookups, schema overlays, approval policy |
| Goals, schedules and background work | Goals, scheduler, async operations, follow-up chains |
| UI and reporting | Workspace UI and appearance, architecture, UI ownership, feeds, MCP UI |
| Client integration | SDK guide, AG-UI operation matrix, iOS, Android |
| Security and persistence | Authentication, authorization policy, conversation model, storage contracts, cleanup |
The Core documentation index links to additional design, configuration and lifecycle references.
| Path | Responsibility |
|---|---|
agently/, cmd/agently/ |
Binary entry point and CLI |
serve.go, runtime/, bootstrap/ |
Server assembly, integrations and defaults |
metadata/, ui/, deployment/ui/ |
Authored metadata, web source and embedded assets |
ios/, android/ |
Native shells and platform dependency selection |
doc/, e2e/, preview/ |
Guides, test workflows and previews |
Custom applications can register tools, connect MCP servers, configure agent resources, extend metadata, or compose their own shell over Core's SDKs. For an embedded runtime, start with the Core architecture guide.
# Build and safely sync web assets, preserving deployment/ui/init.go
(cd ui && npm ci && npm test && npm run build:embed)
go build -o ./bin/agently ./agently
# Native source checks
swift test --package-path ios
(cd android && ./gradlew -Pagently.android.useSiblingSources=true :app:testDebugUnitTest :app:assembleDebug)Web npm sources, Swift package links and Android dependency selection are independent of Go module replacements. Inspect their manifests when developing against sibling sources. Android requires JDK 17 and the Android SDK; iOS device builds require Xcode. Installation, signing and real service-connected tests are covered in the platform guides.
A workspace MCP definition can route tools through an installed Chrome extension instead of a server-side process. Configure this explicitly in the workspace's mcp/<client-name>.yaml; regular server-side MCP clients keep their existing transport.
executionLocation: browser
browserTransport:
type: chrome-extension
extensionId: YOUR_32_LETTER_EXTENSION_ID
portName: mechanize-controller-v1
requestTimeoutMs: 9000
browserTools: ["*"]
outputArtifacts:
mechanize_capture:
name: screenshot.png
role: screenshotReplace the extension ID with the installed provider's ID and use its supported port name. Open the web UI in that Chrome profile and configure the UI origin in the provider's trusted-client settings. The tool catalog is registered through the existing browser MCP connection; the backend does not receive local credential values. The Coder agent includes a generic Mechanize operating skill and discovers application guides through the provider's skills/list and skills/get tools.
Configured captures become owned artifacts before model-visible output. resources/readImage loads them into multimodal input; the screenshot role enables bounded preview resolution and retention of recent screenshots in active context while preserving durable history. See the Core browser MCP design for transport and recovery behavior.
Library Authors:
- Adrian Witas