IBeam.Ai 2.11.0

IBeam.Ai

IBeam.Ai contains the core AI agent, tool, and MCP contracts shared by IBeam-backed applications, plus the vendor-neutral outbound completion contracts under IBeam.Ai.Completions.

Outbound Completions (IBeam.Ai.Completions)

Two halves live in this package family:

• Inbound MCP hosting (external agents calling into an IBeam app) — the contracts below, registered via AddIBeamAiServices.
• Outbound model invocation (an IBeam app calling a model) — IAiCompletionService, registered via AddIBeamAiCompletions(configuration) from IBeam.Ai.Services plus a provider adapter such as IBeam.Ai.Anthropic.

Consumers declare providers and named profiles under IBeam:Ai in configuration (model, effort, max tokens, credit bucket) and inject IAiCompletionService. Switching a feature between models or effort levels is a configuration edit, not a code change. Failure is modelled, not thrown: results carry AiCompletionStatus (Ok, NotConfigured, Refused, Unavailable, Malformed, Filtered, Denied) so a missing API key, a refusal, and a rate limit can each be handled differently. Profiles with a CreditBucketKey are credit-metered through ILicenseCreditGate when it is registered: reserve the estimate, settle actual token usage, release on failure.

dotnet add package IBeam.Ai

When To Use This

• You need agent tool definitions in shared code.
• You are building MCP tools without taking an ASP.NET Core dependency.
• You want a common AgentToolContext for user, tenant, API credential, and agent identity data.
• You are implementing your own MCP orchestration or access policy.

Most host applications should reference IBeam.Ai.Api, which brings the service and core packages transitively.

What This Package Contains

Architecture Fit

API <-- DTO/model object --> Service <-- Entity --> Repository

Agent tools are another API surface. A tool handler should call a service. It should not bypass the service layer to call repositories or embed business permissions directly.

Code Example

var tool = new AgentToolDefinition(
    name: "hubbsly.work.list_cards",
    description: "List work cards visible to the current agent.",
    inputSchema: AgentToolSchemas.EmptyObject(),
    handler: async (context, arguments, ct) =>
    {
        var service = context.Services.GetRequiredService<IWorkItemService>();
        return await service.ListAsync(ct);
    },
    moduleKey: "work",
    requiredScopes: [ "api-scope:work" ]);

Access Control

The core package only defines the policy contract. The default service package policy checks authenticated claims for required scopes/roles/permissions. Applications can replace IAgentToolAccessPolicy to call IBeam AccessControl, Licensing, Identity, or a custom authorization system.

Data Storage

This package does not create tables, repositories, containers, or buckets.

Extended Docs And Agent Guidance

• AI prompt: .agent/prompt.md
• Root implementation guide: ../.agent/implementation-guide.md
• AI enablement kit: ../IBeam.AI.Enablement/README.md
• Agent/API migration prompt: ../IBeam.AI.Enablement/examples/consuming-api-migration-prompt.md
• Service operation permissions: ../docs/service-operation-permissions.md

Agents should keep tool handlers thin and route real work through operation-tagged services.

Version Notes

• Targets net10.0.
• Package version is assigned by the repository release workflow.