agently-core

Agently Core

Agently Core is an embeddable Go framework for building agents that use tools, work with knowledge and data, coordinate other agents, and carry work across conversations and scheduled runs. It provides the execution, policy and durable state behind an agentic application.

Embed it in your service when you want to own the application and integrations. Use Agently for the assembled server, CLI, web application and native mobile shells, with Forge for metadata-driven interfaces.

What Core brings to an agentic application

• Configurable agent behavior. Compose model selection, prompts, intent profiles, knowledge, skills, templates and tool bundles through a workspace. Intake and prompt binding prepare the task for an iterative model/tool loop.
• Tools under a shared policy. Dispatch internal services and MCP tools, govern access, request approvals and collect missing inputs through elicitation. Connect external systems without baking their APIs into the orchestration loop.
• Durable work. Store conversations, turns, messages, calls and execution state. Coordinate queued turns, cancellation, continuation and recovery; keep observer lifetimes separate from running work.
• Agent coordination and autonomous execution. Run linked agents and long-running operations, track conversation goals and budgets, and schedule work through controller-owned turns and distributed scheduler leases.
• Interactive results. Produce canonical transcripts, live tool feeds, hosted workspaces and reports with authored layouts, data sources and visual content. Clients consume these results through AG-UI and application APIs.
• Extensible boundaries. Supply providers, resource finders, tools, integrations and application handlers. Use the Go runtime directly or build web, mobile and CLI clients with the Go, TypeScript, Swift and Kotlin SDKs.

Architecture

The authenticated runtime resolves the task's agent and configuration, creates its durable turn, builds model context and executes the model/tool loop. Tool results become observations for subsequent model calls; approvals and elicitation can suspend work until the required decision or input arrives. Async operations and linked agents retain their invocation relationships.

Execution state and presentation are connected through persisted identities. AG-UI carries conversation runs, messages, tool activity, state and interrupts; Agently extensions carry workspace content, goals, approvals and queued-turn controls. Supporting BFF APIs expose history, resources and application state. Clients can reattach to admitted work while the runtime owns execution and recovery. See the architecture guide for the lifecycle and subsystem boundaries.

Capabilities and guides

Supported adapters include OpenAI, Vertex AI Gemini/Claude, Bedrock Converse/Claude, Grok, InceptionLabs and Ollama. Actual streaming, multimodal input and token-count capabilities depend on the selected provider/model. Context limits and overflow recovery are configurable; optional proactive compaction is described with its agent settings.

Embed the runtime

Requires Go 1.25.8 or newer. Supply configured agent and model finders and the application's authenticated caller identity. This fragment illustrates runtime composition; see the SDK guide for the surrounding setup.

ctx := context.Background()
rt, err := executor.NewBuilder().
    WithAgentFinder(agentFinder).
    WithModelFinder(modelFinder).
    Build(ctx)
if err != nil {
    log.Fatal(err)
}
defer rt.Close(ctx)

backend, err := sdk.NewEmbeddedFromRuntime(rt)
if err != nil {
    log.Fatal(err)
}
out, err := backend.Query(ctx, &agentsvc.QueryInput{
    ConversationID: "conversation-id",
    UserId:         "authenticated-user-id",
    Query:          "Summarize the project documentation",
})

To expose clients over HTTP, create a handler from that backend and configure its authentication for the deployment:

handler, err := sdk.NewHandlerWithContext(ctx, backend)
if err != nil {
    log.Fatal(err)
}
log.Fatal(http.ListenAndServe(":8090", handler))

Client applications use POST /v1/ag-ui/run and its SSE output for conversation interaction. SDKs share the configured authentication/networking for supporting workspace, upload, reporting and history APIs. Refer to the SDK guide for Go, TypeScript, Swift and Kotlin, and the operation matrix for the standard protocol and Agently extension surface.

Workspace and persistence

The default embedded workspace is .agently in the working directory; AGENTLY_WORKSPACE selects another root. A resource ID selects an authored agent, model, tool bundle or other configuration object.

The runtime resolves resources through finders and repositories. Workspace YAML supports reusable imports and scoped parameters; exact parameter substitutions preserve types. Application code can supply custom finders, register internal tool services, add provider adapters or integrate application handlers. Workspace resource APIs support reading and managing authored resources.

Customize behavior by composing agent configuration, tools, knowledge, intent profiles and templates. Customize presentation through application metadata, window definitions, data bindings, actions and themes. Forge is an independent data-driven UI framework used by Agently; Core owns the agent lifecycle and application-facing contracts around rendered content. See the workspace guide, tool system, UI ownership and SDK guide.

SQLite and MySQL persist conversations, execution records, goals, schedules and reports. The runtime preserves ownership and durable operation identity across continuation and cleanup. Scheduler API and runner deployment can be separated with AGENTLY_SCHEDULER_API and AGENTLY_SCHEDULER_RUNNER. Configuration and operational details live in the authentication, scheduler and maintenance guides.

Development

go test ./sdk ./internal/datly/contracttest ./app/store/data
(cd sdk/ts && npm ci && npm run typecheck && npm test)
swift test --package-path sdk/ios
(cd sdk/android && ./gradlew testDebugUnitTest testReleaseUnitTest)

Inspect go.mod and SDK manifests for dependencies. Android requires JDK 17 and the Android SDK; Swift requires its platform toolchain. Live provider, MCP and device tests require their service configuration and credentials.

The documentation index provides the full reading path. LICENSE · NOTICE

Design-system contributions

Start with the canonical usage guide before changing appearance, components or workspace theme contracts. The guide identifies the supported roles, real examples, extension path and existing checks. Include the reused components/roles, specimen and integration evidence, checks and remaining legacy limits in the pull request for shared-owner review.